<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
    <title>Getting Started with BHF Services</title>
    <base href="http://bhs.googlecode.com/svn/trunk/"><!--[if IE]></base><![endif]-->
</head>
<body bgcolor="white">
<p>Blue Hole Framework (BHF) Services are JSON based web Services. Above the J2EE stack you should be fimiliar with
the following underlying technologies, all hosted at Google Code.</p>
    <ul>
        <li><a href="http://json.org/">JSON</a> and the <a href="http://code.google.com/p/bhj/">BHF JSON library</a></li>
        <li><a href="http://code.google.com/p/google-guice/">Google Guice</a></li>
        <li><a href="http://code.google.com/p/bhtx/">BHF Guice Extensions (Projects)</a></li>
    </ul>
<p>The key service concepts are</p>
    <dl>
        <dt>ServiceGroup</dt><dd>A ServiceGroup represents a collection of Services accessed under the
            same ServiceGroup context. In some sense, ServiceGroups partition a Web application and provide a unit of
            resuse within applications. ServiceGroups are used to group Services together for integration into
            one or more applications, to group Services that hacve the same access mechanisms (secure vs. anonymous
            perhaps), to unify exception handling across a group of services, etc. On application initialization
            you must instantiate each application ServiceGroup so that it will be known to the routing process.</dd>
        <dt>Service</dt><dd>You annotate a Service with the <code>Service</code> annotation, provideing at least a name
            for the Service. Each Service is made known to its owning ServiceGroup using the ServiceGroupInfo
            annotation on the ServiceGroup class. A new Service is instantiated for each request; thus, Services
            do not maintain state across requests. Service's can be very simple...
            <pre><code>
@Service( name = "echo", crossSite = true )
public class EchoService
{
    @ServiceMethod()
    public String   echo( final String hello )
    {
        return hello;
    }
}
            </code></pre></dd>
        <dt>Component</dt><dd>Components are Services that have state that spans requests. In a sense,
            Services are like containers of static methods and Components are like objects. A Component's state is
            maintained client side in the browser, but may be cached server side to reduce the impact of state
            transfer. Components must implement the <code>Component</code> interface, perhaps subclassing
            <code>AbstractComponent</code> as a convenience, and must be annotated with the
            <code>ComponentInfo</code> annotation in addition to the <code>Service</code> annotation.</dd>
    </dl>
<h3>Routing</h3>
    <p>Routing is the process of determining which ServiceGroup, Service (and ID if the Service is a Component), and
    Method will be used to fullfill a given request. Most applications will use
    <code>org.bhf.providers.router.DefaultURLRouter</code>, so we will assume this implementation in the example code
    and descriptions. See <a href="javadoc/org/bhf/providers/router/DefaultURLRouter.html">DefaultURLRouter</a> for
    more information.</p>

<h3>Configuring web.xml for BHF services</h3>
    <p>The following is a minimal web.xml for BHF applications. The context listener is for initializing your application,
    including schema migration, Guice injectinos, and ServiceGroups, as applicable. (You can, of course, use a
    different mechanism to initialize your application if you like.) The Controller filter is where BHF comes into play.
    The Controller intercepts any requests that match a route to a Service method and divert to the BHF to field
    the request. All other requests simply pass through the filter and be handled by other filters, servlets, etc.</p>
    <pre><code>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;web-app version="2.4"
             xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" &gt;

        &lt;listener&gt;
            &lt;listener-class&gt;com.acme.app.Application&lt;/listener-class&gt;
        &lt;/listener&gt;

        &lt;filter&gt;
            &lt;filter-name&gt;Controller&lt;/filter-name&gt;
            &lt;filter-class&gt;org.bhf.service.Controller&lt;/filter-class&gt;
        &lt;/filter&gt;

        &lt;filter-mapping&gt;
            &lt;filter-name&gt;Controller&lt;/filter-name&gt;
            &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
        &lt;/filter-mapping&gt;

    &lt;/web-app&gt;
    </code></pre>

    <p>Application initialization must provide a default Injector and instantiate one or more
    <code>ServletGroup</code>s.</p>
    <pre><code>
public class Application implements ServletContextListener
{
    public void contextInitialized( ServletContextEvent event )
    {
        // Service Groups
        final ServiceGroup applicationServiceGroup = new ApplicationServiceGroup();

        // Injectors
        ProjectInjectors.bindDefaultInjector( new Provider&lt;Injector&gt;() {
            public Injector get()
            {
                return Guice.createInjector( new ServiceModule() );
            }
        } );
    }

    public void contextDestroyed( ServletContextEvent event )
    {
    }
}
    </code></pre>
</body>
</html>